KCGetData

KCGetData
Header:	Keychain.h		Carbon status:	Under Evaluation

Determines keychain item data.

OSStatus KCGetData (
    KCItemRef item, 
    UInt32 maxLength, 
    void *data, 
    UInt32 *actualLength
);

Parameter descriptions

item: A reference to the keychain item whose data you wish to determine.
maxLength: The length of the data buffer pointed to by the data parameter.
data: A pointer to a buffer which will hold the returned data. Before calling KCGetData, allocate enough memory for the buffer to hold the data you want to store. On return, a pointer to the attribute data you requested.
actualLength: On return, a pointer to the actual length of the data being retrieved. If the buffer pointed to by data is smaller than the actual length of the data, KCGetData returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling KCGetData again.

function result: A result code. The result code errKCInvalidItemRef indicates that the specified keychain item reference was invalid. The result code errKCBufferTooSmall indicates that your application must allocate a new buffer of sufficient size before calling KCGetData again. The result code errKCDataNotModifiable indicates that the data is not available for this item.

DISCUSSION

You can call KCGetData or the function KCGetAttribute to obtain keychain item data. The difference between the functions is that KCGetAttribute requires that you pass the length of the data and a pointer to that data as fields in a keychain item attribute structure rather than as separate parameters.

If the keychain that contains the item is locked, before calling KCGetData you should call the function KCUnlock to prompt the user to unlock the keychain. You cannot call KCGetData for a private key.

You can determine any of the standard item attributes identified by the following tag constants: kClassKCItemAttr, kCreationDateKCItemAttr, kModDateKCItemAttr, kDescriptionKCItemAttr, kCommentKCItemAttr, kLabelKCItemAttr, kCreatorKCItemAttr, kScriptCodeKCItemAttr, and kCustomIconKCItemAttr. There is additional data you can determine, depending upon the type of keychain item whose data you wish to obtain. See “Keychain Item Data Tag Constants” for more information.

VERSION NOTES

Available beginning with Keychain Manager 1.0.